Converting a Shape to Primitive Form (IM: XG)

Inside Macintosh: QuickDraw GX Graphics /: Chapter 4 - Geometric Operations / Using Geometric Operations

Converting a Shape to Primitive Form
QuickDraw GX requires that certain shapes (such as cap shapes, join shapes, dash shapes, pattern shapes, and clip shapes) be in primitive form--that is, they must have all of their style modifications incorporated into their geometries. Before you set a cap shape, join shape, dash shape, and so on, you must ensure that the shape is in primitive form.
As an example of converting a shape to primitive form, the sample function in
Listing 4-6 creates a polygon shape that is not in primitive form. The polygon has one contour, a closed-frame shape fill, and a pen width of 15.0.
Listing 4-6 Creating an hourglass polygon shape with a thick pen width
void CreateHourglassPolygon(void)
{
   gxShape aPolygonShape;
   gxJoinRecord theJoinRecord;

   static long hourglassGeometry[] = {1, /* number of contours */
                                      4, /* number of points */
                                      ff(50), ff(50),
                                      ff(150), ff(50),
                                      ff(50), ff(150),
                                      ff(150), ff(150)};


   aPolygonShape = GXNewPolygons((gxPolygons *)
                                 hourglassGeometry);
   GXSetShapeFill(aPolygonShape, gxClosedFrameFill);
   GXSetShapePen(aPolygonShape, ff(15));
   
   theJoinRecord.attributes = gxSharpJoin;
   theJoinRecord.join = nil;
   theJoinRecord.miter = gxPositiveInfinity;
   GXSetShapeJoin(aPolygonShape, &theJoinRecord);
   
   GXDrawShape(aPolygonShape);
   GXDisposeShape(aPolygonShape);
}
The result of this sample function is shown in Figure 4-30.
Figure 4-30 A hourglass-shaped polygon with a thick border

The polygon shape defined in Listing 4-6 is not in primitive form because an element of the polygon's style (the pen width) is not incorporated into the polygon's geometry.
QuickDraw GX provides the GXPrimitiveShape function so you can incorporate the elements of a shape's style into the shape's geometry. For example, adding the function call
GXPrimitiveShape(aPolygonShape);
to the sample function in Listing 4-6 creates the polygon shown in Figure 4-31.
Figure 4-31 A polygon shape with style information incorporated into its geometry

As shown in Figure 4-31, the GXPrimitiveShape function has incorporated the pen width into the geometry of the polygon; the resulting polygon has two contours whereas the original had one, and the resulting polygon has a winding fill instead of a closed-frame fill.
Notice that the primitive form of this polygon is not simplified because the GXPrimitiveShape function does not simplify its result. You can simplify the result of this function by calling
GXSimplifyShape(aPolygonShape);
Figure 4-32 shows the resulting shape--the primitive form of the polygon with no crossed or overlapping contours.
Figure 4-32 The primitive form of the polygon shape after simplification

The polygon shape now has three contours--which do not cross or overlap--and yet it appears the same as the original polygon shape when drawn.
For a discussion of style modifications and more examples of the GXPrimitiveShape function, see Chapter 3, "Geometric Styles," in this book.
For more information about the GXPrimitiveShape function, see page 4-79.